iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 7
2
影片教學

想盡辦法當好一個Junior Backend Developer系列 第 7

Golang - 如何當好一個junior backend developer - 談談為何需要API Document

  • 分享至 

  • xImage
  •  

Yes

為什麼需要API Document

  • 需求來了
  • 前後端需要同時開工 後端先寫好API
  • 雙方溝通的文件

何謂API Blueprint

特點

  • 線上寫API文檔的平台
  • 使用Markdown語法撰寫
  • 支援團隊協作
  • 支援Mock Server 方便前端可以透過Mock Data先做
  • 支援版本管理(GitHub)
  • 也可以local運行

缺點

  • 存檔需手動存擋
  • 線上寫文檔UI的反應有點慢
  • 沒有所謂的codegen的tool

何謂Swagger

特點

  • API的開發工具
  • Swagger使用OpenAPI規範, 這個規範由 Linux 基金會主持,是為了建立世界各地共通的 API 規範。
  • 使用語法可以用YAML或者JSON
  • Swagger延伸出來很多工具,例如:Swagger UI, Swagger Editor, Swagger Codegen, Swagger Hub
  • Swagger UI可以拿來自己本地deploy 自己維護API document server
  • Swagger Editor 為線上的編輯器
  • Swagger Codegen 自動產生Client 跟Server 的code 拿去當作Mock Server也可以
  • Swagger Hub 線上文檔平台 提供類似於API Bluepirnt的服務
  • Swagger的生態性相對於API Blueprint豐富很多 找解答會比較好找

針對Swagger Hub來說

  • UI等操作性比API Blueprint好
  • 但免費版的只支持個人 團隊協作需要花錢
  • API Blueprint則是團隊開發可以免費 但有限制數量

總結

  • 一開始的小團隊可以使用API Blueprint工具 整體來說還是比較輕量化
  • 等到前後端都開發成熟後 可以考慮慢慢轉換到Swagger 可控性會更高
  • 這次先用API BluePrint示範 有時間就用Swagger改寫

歡迎參觀團隊其他成員的文章~


上一篇
Golang - 如何當好一個junior backend developer - 來設計貓咪平台的schema吧
下一篇
Golang - 如何當好一個junior backend developer - 介紹如何操作API Blueprint及好用之處
系列文
想盡辦法當好一個Junior Backend Developer13
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言